From df9c469acd64fb12055d3d5fbc35a1e96a3300ad Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 19 Feb 2021 23:33:24 -0500 Subject: [PATCH] video: Convert docs Change link syntax, add an example image, generally clean things up. --- gtk/gtkvideo.c | 115 +++++++++++++++++++++++++------------------------ 1 file changed, 59 insertions(+), 56 deletions(-) diff --git a/gtk/gtkvideo.c b/gtk/gtkvideo.c index f5b6f303e0..8369a296f0 100644 --- a/gtk/gtkvideo.c +++ b/gtk/gtkvideo.c @@ -38,17 +38,19 @@ * @short_description: A widget for displaying video * @see_also: #GtkMediaControls, #GtkMediaStream * - * GtkVideo is a widget to show a #GtkMediaStream with media controls - * as provided by #GtkMediaControls. If you just want to display a - * video without controls, you can treat it like any other paintable - * and for example put it into a #GtkPicture. + * `GtkVideo` is a widget to show a `GtkMediaStream` with media controls. * - * GtkVideo aims to cover use cases such as previews, embedded animations, + * ![An example GtkVideo](video.png) + * + * If you just want to display a video without controls, you can treat it + * like any other paintable and for example put it into a [class@Gtk.Picture]. + * + * `GtkVideo` aims to cover use cases such as previews, embedded animations, * etc. It supports autoplay, looping, and simple media controls. It does * not have support for video overlays, multichannel audio, device * selection, or input. If you are writing a full-fledged video player, - * you may want to use the #GdkPaintable API and a media framework such - * as Gstreamer directly. + * you may want to use the [class@Gdk.Paintable] API and a media framework + * such as Gstreamer directly. */ struct _GtkVideo @@ -367,10 +369,10 @@ gtk_video_init (GtkVideo *self) /** * gtk_video_new: * - * Creates a new empty #GtkVideo. + * Creates a new empty `GtkVideo`. * - * Returns: a new #GtkVideo - **/ + * Returns: a new `GtkVideo` + */ GtkWidget * gtk_video_new (void) { @@ -379,12 +381,12 @@ gtk_video_new (void) /** * gtk_video_new_for_media_stream: - * @stream: (allow-none): a #GtkMediaStream + * @stream: (allow-none): a `GtkMediaStream` * - * Creates a #GtkVideo to play back the given @stream. + * Creates a `GtkVideo` to play back the given @stream. * - * Returns: a new #GtkVideo - **/ + * Returns: a new `GtkVideo` + */ GtkWidget * gtk_video_new_for_media_stream (GtkMediaStream *stream) { @@ -397,12 +399,12 @@ gtk_video_new_for_media_stream (GtkMediaStream *stream) /** * gtk_video_new_for_file: - * @file: (allow-none): a #GFile + * @file: (allow-none): a `GFile` * - * Creates a #GtkVideo to play back the given @file. + * Creates a `GtkVideo` to play back the given @file. * - * Returns: a new #GtkVideo - **/ + * Returns: a new `GtkVideo` + */ GtkWidget * gtk_video_new_for_file (GFile *file) { @@ -417,13 +419,13 @@ gtk_video_new_for_file (GFile *file) * gtk_video_new_for_filename: * @filename: (allow-none) (type filename): filename to play back * - * Creates a #GtkVideo to play back the given @filename. + * Creates a `GtkVideo` to play back the given @filename. * - * This is a utility function that calls gtk_video_new_for_file(), + * This is a utility function that calls [ctor@Gtk.Video.new_for_file], * See that function for details. * - * Returns: a new #GtkVideo - **/ + * Returns: a new `GtkVideo` + */ GtkWidget * gtk_video_new_for_filename (const char *filename) { @@ -447,13 +449,13 @@ gtk_video_new_for_filename (const char *filename) * gtk_video_new_for_resource: * @resource_path: (allow-none): resource path to play back * - * Creates a #GtkVideo to play back the resource at the + * Creates a `GtkVideo` to play back the resource at the * given @resource_path. * - * This is a utility function that calls gtk_video_new_for_file(), + * This is a utility function that calls [ctor@Gtk.Video.new_for_file]. * - * Returns: a new #GtkVideo - **/ + * Returns: a new `GtkVideo` + */ GtkWidget * gtk_video_new_for_resource (const char *resource_path) { @@ -487,12 +489,12 @@ gtk_video_new_for_resource (const char *resource_path) /** * gtk_video_get_media_stream: - * @self: a #GtkVideo + * @self: a `GtkVideo` * * Gets the media stream managed by @self or %NULL if none. * * Returns: (nullable) (transfer none): The media stream managed by @self - **/ + */ GtkMediaStream * gtk_video_get_media_stream (GtkVideo *self) { @@ -578,16 +580,18 @@ gtk_video_notify_cb (GtkMediaStream *stream, /** * gtk_video_set_media_stream: - * @self: a #GtkVideo + * @self: a `GtkVideo` * @stream: (allow-none): The media stream to play or %NULL to unset * - * Sets the media stream to be played back. @self will take full control - * of managing the media stream. If you want to manage a media stream - * yourself, consider using a #GtkImage for display. + * Sets the media stream to be played back. * - * If you want to display a file, consider using gtk_video_set_file() + * @self will take full control of managing the media stream. If you + * want to manage a media stream yourself, consider using a + * [class@Gtk.Picture] for display. + * + * If you want to display a file, consider using [method@Gtk.Video.set_file] * instead. - **/ + */ void gtk_video_set_media_stream (GtkVideo *self, GtkMediaStream *stream) @@ -647,13 +651,13 @@ gtk_video_set_media_stream (GtkVideo *self, /** * gtk_video_get_file: - * @self: a #GtkVideo + * @self: a `GtkVideo` * * Gets the file played by @self or %NULL if not playing back * a file. * * Returns: (nullable) (transfer none): The file played by @self - **/ + */ GFile * gtk_video_get_file (GtkVideo *self) { @@ -664,11 +668,11 @@ gtk_video_get_file (GtkVideo *self) /** * gtk_video_set_file: - * @self: a #GtkVideo + * @self: a `GtkVideo` * @file: (allow-none): the file to play * * Makes @self play the given @file. - **/ + */ void gtk_video_set_file (GtkVideo *self, GFile *file) @@ -711,13 +715,13 @@ gtk_video_set_file (GtkVideo *self, /** * gtk_video_set_filename: - * @self: a #GtkVideo + * @self: a `GtkVideo` * @filename: (allow-none): the filename to play * * Makes @self play the given @filename. * * This is a utility function that calls gtk_video_set_file(), - **/ + */ void gtk_video_set_filename (GtkVideo *self, const char *filename) @@ -739,13 +743,13 @@ gtk_video_set_filename (GtkVideo *self, /** * gtk_video_set_resource: - * @self: a #GtkVideo + * @self: a `GtkVideo` * @resource_path: (allow-none): the resource to set * * Makes @self play the resource at the given @resource_path. * - * This is a utility function that calls gtk_video_set_file(), - **/ + * This is a utility function that calls [method@Gtk.Video.set_file]. + */ void gtk_video_set_resource (GtkVideo *self, const char *resource_path) @@ -779,12 +783,12 @@ gtk_video_set_resource (GtkVideo *self, /** * gtk_video_get_autoplay: - * @self: a #GtkVideo + * @self: a `GtkVideo` * - * Returns %TRUE if videos have been set to loop via gtk_video_set_loop(). + * Returns %TRUE if videos have been set to loop. * * Returns: %TRUE if streams should autoplay - **/ + */ gboolean gtk_video_get_autoplay (GtkVideo *self) { @@ -795,12 +799,12 @@ gtk_video_get_autoplay (GtkVideo *self) /** * gtk_video_set_autoplay: - * @self: a #GtkVideo + * @self: a `GtkVideo` * @autoplay: whether media streams should autoplay * - * Sets whether @self automatically starts playback when it becomes visible - * or when a new file gets loaded. - **/ + * Sets whether @self automatically starts playback when it + * becomes visible or when a new file gets loaded. + */ void gtk_video_set_autoplay (GtkVideo *self, gboolean autoplay) @@ -817,12 +821,12 @@ gtk_video_set_autoplay (GtkVideo *self, /** * gtk_video_get_loop: - * @self: a #GtkVideo + * @self: a `GtkVideo` * - * Returns %TRUE if videos have been set to loop via gtk_video_set_loop(). + * Returns %TRUE if videos have been set to loop. * * Returns: %TRUE if streams should loop - **/ + */ gboolean gtk_video_get_loop (GtkVideo *self) { @@ -833,11 +837,11 @@ gtk_video_get_loop (GtkVideo *self) /** * gtk_video_set_loop: - * @self: a #GtkVideo + * @self: a `GtkVideo` * @loop: whether media streams should loop * * Sets whether new files loaded by @self should be set to loop. - **/ + */ void gtk_video_set_loop (GtkVideo *self, gboolean loop) @@ -851,4 +855,3 @@ gtk_video_set_loop (GtkVideo *self, g_object_notify_by_pspec (G_OBJECT (self), properties[PROP_LOOP]); } - -- 2.30.2